Passport OCR API

Objective

Input	Output
An image or PDF file containing a user's Vietnamese passport.	The textual information extracted from the document.

API URL

https://apac.docs.hyperverge.co/v1/readVNPassport

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
Content-type	Mandatory	This parameter defines the media type for the request payload.	multipart/form-data
appId	Mandatory	Application ID shared by HyperVerge	Not Applicable - this is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	Not Applicable - this is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs

The following table provides the details of the fields required for the API's request body:

Parameter	Mandatory or Optional	Description	Valid Values
image1	Mandatory	The image or PDF file on which the API will perform the OCR extraction.	The API supports JPEG, PNG and TIFF images. Input Image Constraints For the deep learning servers to extract text out of an image, the rule of thumb that needs to be followed is that the text in the image should be legible. Higher size of image will lead to higher upload and processing time. Hence the size of image should be reduced as much as possible while ensuring that above condition is met. A general guideline that can be followed is to keep the width of the ID card image at least 800 pixels and to keep JPEG compression quality factor above 80%. The aspect ratio of the input image should be same as the aspect ratio of the original document. Kindly take care of the aspect ratio when resizing the image. If integrating into an Android or iOS app, please use the HyperSnap SDK for Android and iOS. This SDK provides camera functionality for capturing images of ID cards while taking care of all the above requirements.

Sample Request

The following code shows a standard curl request for the API:

curl --location --request POST 'https://apac.docs.hyperverge.co/v1/readVNPassport' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image1=@"<path_to_passport_image>"'

Success Response Sample

The following code is a sample of success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "type": "vn_passport_front",
      "details": {
        "place_of_issue": {
          "to-be-reviewed": "no",
          "value": "xyz",
          "conf": 0.99
        },
        "passport_num": {
          "to-be-reviewed": "no",
          "value": "xyz",
          "conf": 1
        },
        "type": {
          "to-be-reviewed": "no",
          "value": "P",
          "conf": 1
        },
        "name": {
          "to-be-reviewed": "no",
          "value": "xyz",
          "conf": 1
        },
        "dob": {
          "to-be-reviewed": "no",
          "value": "12/09/1995",
          "conf": 1
        },
        "gender": {
          "to-be-reviewed": "no",
          "value": "NAM/M",
          "conf": 1
        },
        "doe": {
          "to-be-reviewed": "no",
          "value": "17/02/2021",
          "conf": 1
        },
        "doi": {
          "to-be-reviewed": "no",
          "value": "17/02/2011",
          "conf": 1
        },
        "country_code": {
          "to-be-reviewed": "no",
          "value": "VNM",
          "conf": 1
        },
        "place_of_birth": {
          "to-be-reviewed": "no",
          "value": "xyz",
          "conf": 1
        },
        "nationality": {
          "to-be-reviewed": "no",
          "value": "VIETNAMESE",
          "conf": 0.99
        },
        "fraudCheck": {
          "isBlackWhite": {
            "to-be-reviewed": "no",
            "value": "no",
            "conf": 1
          }
        },
        "id": {
          "to-be-reviewed": "no",
          "value": "xyz",
          "conf": 1
        }
      }
    }
  ],
  "requestId": "1660644264220-76573215-f051-477f-ab10-0c8de6b2b350"
}

Failure Response Sample

The following is a sample failure response where the API fails to detect a document from the image.

{
 	"status": "failure",
 	"statusCode": "422",
 	"error": "Passport not Detected",
 	"requestId": "<Random_String_Identifier>"
 }

Error Response Sample

The following are the sample error responses for the API.

Missing Input

{
	"status": "failure",
	"statusCode": "400",
  "error": "API call requires atlest one input image"
}

Over Rate Limit

{
  "status": "failure",
  "statusCode": "429",
  "error": "Rate limit exceeded"
}

Missing/Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure",
  "metaData": {
      "requestId": "123456789",
      "transactionId": "abcd"
  }
}

Missing/Invalid Credentials

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error",
  "metaData": {
    "requestId": "123456789",
    "transactionId": "abcd"
  }
}

Failure and Error Response Details

This API can return failure or error responses with relevant status codes and error messages. Below is a table listing all possible responses.

Status Code	Error Message	Error Description
400	API call requires at least one input image	The API request is missing input images, which is a required parameter.
422	Passport not Detected	The API failed to detect a passport from the provided image.
429	Rate limit exceeded	The API usage rate limit has been exceeded.
401	Missing/Invalid credentials	The request either lacks mandatory credentials or contains invalid ones.
500	Internal Server Error	An internal server error occurred. Please contact support with requestId and transactionId for assistance.